Kubernetes Operator开发超详细指南
一、前言:什么是 Operator?
1.1 Operator 的本质
想象一下,如果你有一个复杂的应用,比如数据库集群,你需要手动执行很多操作:部署、配置、升级、备份、故障恢复等等。这些操作需要专业的运维知识,而且容易出错。
Operator 就是为了解决这个问题而生的。它是一种 Kubernetes 扩展,能够将特定应用的运维知识编码到软件中,实现应用的自动化管理。
简单来说,Operator = 自定义资源(CRD) + 控制器(Controller) + 应用运维知识
1.2 为什么需要 Operator?
- 自动化管理:自动执行应用的部署、配置、升级等操作
- 一致性:确保应用在不同环境中的配置和状态一致
- 减少人为错误:避免手动操作带来的失误
- 标准化:将最佳实践编码到软件中,确保应用按照标准方式运行
- 可扩展性:可以根据应用的特性定制管理逻辑
1.3 Operator 的工作原理
Operator 的工作基于 Kubernetes 的控制器模式,核心是一个调谐循环(Reconcile Loop):
- 观察期望状态:读取自定义资源(CR)中定义的期望状态(Spec)
- 观察实际状态:检查集群中应用的实际状态
- 调谐:如果实际状态与期望状态不一致,执行操作使它们一致
这个过程会持续运行,确保应用始终保持在期望的状态。
二、准备工作:环境搭建
2.1 安装必要工具
- Go:Operator 开发使用 Go 语言,需要安装 Go 1.20 或更高版本
- kubectl:Kubernetes 的命令行工具,用于与集群交互
- kind:用于在本地运行 Kubernetes 集群的工具,非常适合开发和测试
- kubebuilder:用于构建 Kubernetes API 扩展和控制器的框架,是开发 Operator 的必备工具
2.2 创建本地 Kubernetes 集群
参考 基于Kind搭建测试集群 创建一个本地高可用 Kubernetes 集群,用于开发和测试。
集群配置:
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
networking:
apiServerAddress: "192.168.1.13"
nodes:
- role: control-plane
extraPortMappings:
- containerPort: 6443
hostPort: 6443
listenAddress: "192.168.1.13"
protocol: tcp
- role: control-plane
- role: control-plane
- role: worker
- role: worker
- role: worker
创建集群:
sudo kind create cluster --config=kind-config.yaml --name my-test --image kindest/node:v1.34.0 --retain
sudo kubectl cluster-info --context kind-my-test
2.3 配置 Go 环境变量
go env -w GO111MODULE=on
go env -w GOPROXY=https://goproxy.cn,direct
三、项目初始化:创建 Operator 项目
3.1 初始化项目结构
mkdir -p ~/workspace/operator/myapp-operator
cd ~/workspace/operator/myapp-operator
kubebuilder init --domain example.com --repo myapp-operator
3.2 查看项目结构
.
├── cmd/ # 命令行入口
├── config/ # 配置文件
├── hack/ # 脚本文件
├── test/ # 测试文件
├── Dockerfile # Docker构建文件
├── Makefile # 构建脚本
├── PROJECT # 项目元数据
├── go.mod # Go模块文件
└── go.sum # Go依赖校验文件
3.3 创建 API 和控制器
kubebuilder create api --group apps --version v1 --kind MyApp
执行时 kubebuilder 会提示是否创建资源和控制器,都选择 y。
新增的关键文件:
api/v1/myapp_types.go:定义了 MyApp 资源的类型api/v1/groupversion_info.go:定义了 API 组和版本信息internal/controller/myapp_controller.go:实现了 MyApp 资源的控制器逻辑internal/controller/myapp_controller_test.go:控制器的测试文件
四、CRD 定义:定义自定义资源
4.1 理解 CRD 结构
CRD(Custom Resource Definition)是自定义资源的定义,它扩展了 Kubernetes API,允许我们创建和管理自定义资源。
在 api/v1/myapp_types.go 文件中,kubebuilder 生成的默认结构:
package v1
import (
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)
// MyAppSpec defines the desired state of MyApp
type MyAppSpec struct {
// +optional
Foo *string `json:"foo,omitempty"`
}
// MyAppStatus defines the observed state of MyApp.
type MyAppStatus struct {
// +listType=map
// +listMapKey=type
// +optional
Conditions []metav1.Condition `json:"conditions,omitempty"`
}
// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// MyApp is the Schema for the myapps API
type MyApp struct {
metav1.TypeMeta `json:",inline"`
metav1.ObjectMeta `json:"metadata,omitempty,omitzero"`
Spec MyAppSpec `json:"spec"`
Status MyAppStatus `json:"status,omitempty,omitzero"`
}
// +kubebuilder:object:root=true
// MyAppList contains a list of MyApp
type MyAppList struct {
metav1.TypeMeta `json:",inline"`
metav1.ListMeta `json:"metadata,omitempty"`
Items []MyApp `json:"items"`
}
func init() {
SchemeBuilder.Register(&MyApp{}, &MyAppList{})
}
4.2 修改 CRD 定义
修改 MyApp 资源的定义,创建一个简单的应用管理资源,用于部署和管理 Nginx 应用:
// MyAppSpec defines the desired state of MyApp
type MyAppSpec struct {
// 应用名称
AppName string `json:"appName,omitempty"`
// 副本数
Replicas int32 `json:"replicas,omitempty"`
// 镜像信息
Image string `json:"image,omitempty"`
// 端口信息
Port int32 `json:"port,omitempty"`
}
// MyAppStatus defines the observed state of MyApp
type MyAppStatus struct {
// 部署状态
Status string `json:"status,omitempty"`
// 可用副本数
AvailableReplicas int32 `json:"availableReplicas,omitempty"`
// 服务URL
ServiceURL string `json:"serviceURL,omitempty"`
}
4.3 生成代码和 CRD 清单
# 生成 DeepCopy 方法
make generate
# 生成 CRD 清单文件(config/crd/bases/)和 RBAC 规则(config/rbac/)
make manifests
五、控制器开发:编写调谐逻辑
5.1 理解控制器结构
控制器是 Operator 的核心,负责监控自定义资源的变化,并执行调谐逻辑。kubebuilder 生成的默认结构:
// MyAppReconciler reconciles a MyApp object
type MyAppReconciler struct {
client.Client
Scheme *runtime.Scheme
}
// +kubebuilder:rbac:groups=apps.example.com,resources=myapps,verbs=get;list;watch;create;update;patch;delete
// +kubebuilder:rbac:groups=apps.example.com,resources=myapps/status,verbs=get;update;patch
// +kubebuilder:rbac:groups=apps.example.com,resources=myapps/finalizers,verbs=update
func (r *MyAppReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
_ = logf.FromContext(ctx)
// TODO(user): your logic here
return ctrl.Result{}, nil
}
func (r *MyAppReconciler) SetupWithManager(mgr ctrl.Manager) error {
return ctrl.NewControllerManagedBy(mgr).
For(&appsv1.MyApp{}).
Named("myapp").
Complete(r)
}
5.2 编写调谐逻辑
实现 Reconcile 函数的逻辑,目标:
- 当创建 MyApp 资源时,自动创建对应的 Deployment 和 Service
- 当更新 MyApp 资源时,自动更新对应的 Deployment 和 Service
- 当删除 MyApp 资源时,自动删除对应的 Deployment 和 Service(通过 OwnerReference)
- 更新 MyApp 资源的状态,反映实际的部署情况
import (
"context"
"fmt"
"k8s.io/apimachinery/pkg/api/errors"
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
"k8s.io/apimachinery/pkg/runtime"
"k8s.io/apimachinery/pkg/types"
appsv1 "k8s.io/api/apps/v1"
corev1 "k8s.io/api/core/v1"
ctrl "sigs.k8s.io/controller-runtime"
"sigs.k8s.io/controller-runtime/pkg/client"
"sigs.k8s.io/controller-runtime/pkg/log"
apps "myapp-operator/api/v1"
)
func (r *MyAppReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
logger := log.FromContext(ctx)
logger.Info("开始处理MyApp资源", "name", req.Name, "namespace", req.Namespace)
// 1. 获取MyApp资源
var myapp apps.MyApp
if err := r.Get(ctx, req.NamespacedName, &myapp); err != nil {
if errors.IsNotFound(err) {
logger.Info("MyApp资源不存在,可能已被删除")
return ctrl.Result{}, nil
}
return ctrl.Result{}, err
}
// 2. 处理Deployment
deploymentName := fmt.Sprintf("%s-deployment", myapp.Name)
deployment := &appsv1.Deployment{
ObjectMeta: metav1.ObjectMeta{
Name: deploymentName,
Namespace: myapp.Namespace,
Labels: map[string]string{"app": myapp.Name},
},
Spec: appsv1.DeploymentSpec{
Replicas: &myapp.Spec.Replicas,
Selector: &metav1.LabelSelector{
MatchLabels: map[string]string{"app": myapp.Name},
},
Template: corev1.PodTemplateSpec{
ObjectMeta: metav1.ObjectMeta{
Labels: map[string]string{"app": myapp.Name},
},
Spec: corev1.PodSpec{
Containers: []corev1.Container{
{
Name: myapp.Name,
Image: myapp.Spec.Image,
Ports: []corev1.ContainerPort{
{ContainerPort: myapp.Spec.Port},
},
},
},
},
},
},
}
// 设置OwnerReference,确保Deployment随MyApp资源一起删除
if err := ctrl.SetControllerReference(&myapp, deployment, r.Scheme); err != nil {
return ctrl.Result{}, err
}
// 检查Deployment是否存在
var existingDeployment appsv1.Deployment
err := r.Get(ctx, types.NamespacedName{Name: deploymentName, Namespace: myapp.Namespace}, &existingDeployment)
if err != nil {
if errors.IsNotFound(err) {
logger.Info("创建Deployment", "name", deploymentName)
if err := r.Create(ctx, deployment); err != nil {
return ctrl.Result{}, err
}
} else {
return ctrl.Result{}, err
}
} else {
logger.Info("更新Deployment", "name", deploymentName)
existingDeployment.Spec = deployment.Spec
if err := r.Update(ctx, &existingDeployment); err != nil {
return ctrl.Result{}, err
}
}
// 3. 处理Service
serviceName := fmt.Sprintf("%s-service", myapp.Name)
service := &corev1.Service{
ObjectMeta: metav1.ObjectMeta{
Name: serviceName,
Namespace: myapp.Namespace,
Labels: map[string]string{"app": myapp.Name},
},
Spec: corev1.ServiceSpec{
Selector: map[string]string{"app": myapp.Name},
Ports: []corev1.ServicePort{
{Port: myapp.Spec.Port, Protocol: corev1.ProtocolTCP},
},
Type: corev1.ServiceTypeClusterIP,
},
}
if err := ctrl.SetControllerReference(&myapp, service, r.Scheme); err != nil {
return ctrl.Result{}, err
}
var existingService corev1.Service
err = r.Get(ctx, types.NamespacedName{Name: serviceName, Namespace: myapp.Namespace}, &existingService)
if err != nil {
if errors.IsNotFound(err) {
logger.Info("创建Service", "name", serviceName)
if err := r.Create(ctx, service); err != nil {
return ctrl.Result{}, err
}
} else {
return ctrl.Result{}, err
}
} else {
logger.Info("更新Service", "name", serviceName)
existingService.Spec = service.Spec
if err := r.Update(ctx, &existingService); err != nil {
return ctrl.Result{}, err
}
}
// 4. 更新MyApp资源的状态
if err := r.Get(ctx, types.NamespacedName{Name: deploymentName, Namespace: myapp.Namespace}, &existingDeployment); err != nil {
return ctrl.Result{}, err
}
if err := r.Get(ctx, types.NamespacedName{Name: serviceName, Namespace: myapp.Namespace}, &existingService); err != nil {
return ctrl.Result{}, err
}
myapp.Status.Status = "Running"
myapp.Status.AvailableReplicas = existingDeployment.Status.AvailableReplicas
myapp.Status.ServiceURL = fmt.Sprintf("%s.%s.svc.cluster.local:%d",
existingService.Name, existingService.Namespace, myapp.Spec.Port)
if err := r.Status().Update(ctx, &myapp); err != nil {
return ctrl.Result{}, err
}
logger.Info("MyApp资源处理完成", "name", myapp.Name)
return ctrl.Result{}, nil
}
5.3 注册控制器
确保控制器在 Manager 中正确注册(cmd/main.go):
// 注册MyApp控制器
if err = (&controller.MyAppReconciler{
Client: mgr.GetClient(),
Scheme: mgr.GetScheme(),
}).SetupWithManager(mgr); err != nil {
setupLog.Error(err, "unable to create controller", "controller", "MyApp")
os.Exit(1)
}
六、部署和测试:验证 Operator 功能
6.1 安装 CRD 并本地运行
# 安装 CRD 到集群
make install
# 本地运行控制器(开发调试用)
export ENABLE_WEBHOOKS=false
make run
6.2 创建测试资源
apiVersion: apps.example.com/v1
kind: MyApp
metadata:
name: myapp-test
namespace: default
spec:
appName: nginx-test
replicas: 2
image: nginx:latest
port: 80
kubectl apply -f myapp-test.yaml
6.3 验证部署结果
kubectl get myapp
kubectl describe myapp myapp-test
kubectl get deployment
kubectl get pods
kubectl get service
预期结果:
- MyApp 资源状态为 "Running"
- Deployment 被创建,副本数为 2
- Pod 状态为 "Running"
- Service 被创建
6.4 更新和删除测试
更新副本数:
# 修改 replicas 为 3 后
kubectl apply -f myapp-test.yaml
kubectl get pods # 应该看到 3 个 Pod
删除资源:
kubectl delete -f myapp-test.yaml
kubectl get deployment # 所有相关资源应被级联删除
七、构建和部署:将 Operator 部署到集群
7.1 构建镜像
make docker-build IMG=myapp-operator:v1.0.0
7.2 加载镜像到 kind 集群
kind load docker-image myapp-operator:v1.0.0 --name my-test
7.3 部署到集群
make deploy IMG=myapp-operator:v1.0.0
7.4 验证部署
kubectl get deployment -n myapp-operator-system
kubectl get pods -n myapp-operator-system
kubectl get service -n myapp-operator-system
八、常见问题和解决方案
8.1 连接集群失败
错误:dial tcp 127.0.0.1:8080: connect: connection refused
解决:确保 kubeconfig 文件正确配置。对于 kind 集群:
kind export kubeconfig --name=my-test --kubeconfig=$HOME/.kube/config
kubectl cluster-info
8.2 CRD 注解过长
错误:metadata.annotations: Too long: must have at most 262144 bytes
解决:修改 Makefile,在 manifests 命令中添加 crd:maxDescLen=0:
.PHONY: manifests
manifests: controller-gen
$(CONTROLLER_GEN) rbac:roleName=manager-role crd:maxDescLen=0 webhook paths="./..." output:crd:artifacts:config=config/crd/bases
8.3 Webhook 证书问题
错误:failed to get webhook server certificate
解决:
- 开发环境:
export ENABLE_WEBHOOKS=false - 生产环境:安装 cert-manager 并正确配置 Webhook 证书
8.4 控制器启动失败
错误:unable to create controller
排查步骤:
- 检查控制器代码语法
- 检查依赖是否正确安装
- 检查 RBAC 权限配置
- 查看日志:
kubectl logs -n myapp-operator-system deployment/myapp-operator-controller-manager
九、总结
通过本指南,我们学习了如何从零开始开发一个 Kubernetes Operator:
- 环境搭建和准备
- 项目初始化和结构创建
- CRD 定义和控制器开发
- 部署和测试
- 常见问题和解决方案
资源推荐
- Kubernetes 官方文档:https://kubernetes.io/docs/
- Operator SDK 文档:https://sdk.operatorframework.io/docs/
- Kubebuilder 文档:https://book.kubebuilder.io/
- Controller Runtime 文档:https://pkg.go.dev/sigs.k8s.io/controller-runtime